Adding Items With the Unique Items Attribute Set (IM: XG)

Inside Macintosh: QuickDraw GX Graphics /: Chapter 6 - Picture Shapes / Using Picture Shapes

Adding Items With the Unique Items Attribute Set
The unique items shape attribute changes the way in which QuickDraw GX adds shapes to a picture. When you add a shape to a picture that does not have this attribute set, QuickDraw GX copies the reference to the existing shape, inserts this reference into the picture's item list, and increments the owner count of the shape. Similarly, if you specify an overriding style, ink, or transform object for the shape, QuickDraw GX copies the object's reference into the picture's item list and increments the owner count of the object.
However, when you add a shape to a picture that has the unique items attribute set, QuickDraw GX makes a copy of the shape and inserts a reference to the copy in the picture's item list. Similarly, overriding styles, inks, and transforms are also copied.
As an example, Listing 6-13 shows how to use the GXGetShapeAttributes and GXSetShapeAttributes functions to set the unique items shape attribute of a picture. You must set this attribute before you add any items to a picture; if the picture already contains items, setting this attribute results in an error.
This listing adds four instances of a window rectangle to the house picture from
Listing 6-1 on page 6-28. This sample code specifies the same overriding transform for each instance of the window rectangle. However, the overriding transform is moved (with the GXMoveTransform function) after each call to the AddToPicture library function. Because the house picture has the unique items shape attribute set, QuickDraw GX makes a separate copy of the overriding transform each time a window rectangle is inserted into the picture.
Listing 6-13 Adding unique items to a picture
GXSetShapeAttributes(housePicture,
   GXGetShapeAttributes(housePicture) | gxUniqueItemsShape);
.
.
.
moveToRight = GXNewTransform();

for (count = 0; count <= 3 ; count++) {
   AddToPicture(housePicture, 
                windowRectangle, 
                nil, nil, 
                moveToRight);
   GXMoveTransform(moveToRight, ff(7), 0);
}
In this example, the first time that the AddToPicture function is called, QuickDraw GX creates a copy of the window rectangle shape and a copy of the overriding transform object, and inserts references to the copies in the item list of the house picture.
The second time that the AddToPicture function is called, QuickDraw GX notices that the window rectangle shape has not changed, so it does not make another copy of the window rectangle. Instead, it creates a new item in the house picture that references the previously made copy. However, the overriding transform has changed, so QuickDraw GX makes a new copy of it for the new picture item.
The third and fourth calls to the AddToPicture function also create new copies of the overriding transform, but do not create new copies of the window rectangle.
After the code from Listing 6-13 finishes executing, there are a total of two window rectangles--the original one, which is referenced by the windowRectangle variable, and the copy, which is referenced four times by the items of the house picture. There are a total of five transform objects--the original one, which is referenced by the moveToRight variable, and four separate copies referenced by the four new items of the picture.
Figure 6-26 shows the resulting picture.
Figure 6-26 A house with four windows and four unique overriding transforms

For more information about the unique items shape attribute, see "Unique Items Shape Attribute" beginning on page 6-15.